home *** CD-ROM | disk | FTP | other *** search
/ Steal This CD / steal_this_cd.iso / Chapter 07 - Where the Hackers Are / virc200.exe / {app} / vircdll.txt < prev    next >
Text File  |  2003-05-16  |  6KB  |  176 lines
  1. ViRC DLL Interface
  2. Jesse McGrew
  3. June 6, 2001
  4.  
  5. Introduction
  6. ============
  7.  
  8. ViRC 2.0 can call functions from a DLL, using the /dll command or the
  9. $dll() function. Since 2.0pre8, it works with two types of DLLs:
  10. mIRC compatible DLLs, which don't stay loaded in memory, and ViRC
  11. persistent DLLs, which do.
  12.  
  13. Please note that the C definitions below are provided for convenience
  14. only, have not been officially tested, and may be incorrect.
  15.  
  16. mIRC Compatible DLLs
  17. ====================
  18.  
  19. Although not all mIRC DLLs will work in ViRC, the same format as
  20. mIRC's DLLs can be used:
  21.  
  22.   // Delphi
  23.   function ProcName(Main, Active: HWND; Data, Params: PChar; Show,
  24.     NoPause: BOOL): Integer; stdcall;
  25.  
  26.   // C
  27.   int FAR PASCAL procname(HWND main, HWND active, char *data, char *params,
  28.                           BOOL show, BOOL nopause)
  29.  
  30. Main and Active are the window handles of the main ViRC form and the
  31. active form (server/channel/query/DCC chat) that invoked the DLL function.
  32. Data is used to pass arguments between the DLL and ViRC. Params is only
  33. used by ViRC to pass the version number.
  34.  
  35. The DLL can detect whether it was called from ViRC by checking the Params
  36. buffer. ViRC initializes it to "ViRC 200", where 200 is the current ViRC
  37. build.
  38.  
  39. The DLL function must return a value between 0 and 3:
  40. 0 or 1 - no value is returned to the script. ViRC treats 0 and 1 the same.
  41. 2 - no value is returned, but the Data buffer contains a command to run
  42.     before returning to the script.
  43. 3 - the Data buffer contains a string to return to the script.
  44.  
  45. Persistent DLLs
  46. ===============
  47.  
  48. The $LoadDLL() function loads a persistent DLL and returns a handle. This
  49. handle can be used to call procedures from the library, or to unload it:
  50.  
  51.   @ $handle = $LoadDLL(fpu.dll)
  52.   @l $sum = $DLL($handle fadd 1.23 4.56)
  53.   FreeDLL $handle
  54.  
  55. When ViRC loads a persistent DLL, it calls the VSPersist function:
  56.  
  57.   // Delphi
  58.   function VSPersist(Params: PChar; InitStruct: PDLLInitStruct): Integer;
  59.     stdcall;
  60.   
  61.   // C
  62.   int FAR PASCAL VSPersist(char *params, DLLINITSTRUCT *initstruct)
  63.  
  64. If the DLL does not export a VSPersist function, it will still be loaded.
  65.  
  66. The InitStruct parameter is a pointer to a TDLLInitStruct structure, which
  67. contains information about the client and callback functions for the DLL
  68. to use:
  69.  
  70.   // Delphi
  71.   TDLLExecProc = procedure (Text: PChar) stdcall;
  72.   TDLLParseVarsProc = function (Text, Buffer: PChar; 
  73.     BufSize: Integer): Integer stdcall;
  74.   TDLLDirectAliasProc = procedure (Token, AliasName, ProcName: PChar) stdcall;
  75.  
  76.   PDLLInitStruct = ^TDLLInitStruct;
  77.   TDLLInitStruct = packed record
  78.     StructVer, StructSize: Word;
  79.     ClientBuild, ClientPre: Word;
  80.     ClientName, DLLToken: packed array[0..15] of Char;
  81.     MainHWND, ClientHWND: HWND;
  82.     // callback routines
  83.     IRCExec: TDLLExecProc;
  84.     Execute: TDLLExecProc;
  85.     ParseVars: TDLLParseVarsProc;
  86.     DirectAlias: TDLLDirectAliasProc;
  87.   end;
  88.   
  89.   // C
  90.   typedef void FAR PASCAL (*DLLExecProc)(char *text);
  91.   typedef int FAR PASCAL (*DLLParseVarsProc)(char *text, char *buffer, 
  92.     int bufsize);
  93.   typedef void FAR PASCAL (*DLLDirectAliasProc)(char *token, char *aliasname,
  94.     char *procname);
  95.   
  96.   typedef struct {
  97.     WORD StructVer, StructSize;
  98.     WORD ClientBuild, ClientPre;
  99.     char ClientName[16], DLLToken[16];
  100.     HWND MainHWND, ClientHWND;
  101.     // callback routines
  102.     DLLExecProc IRCExec;
  103.     DLLExecProc Execute;
  104.     DLLParseVarsProc ParseVars;
  105.     DLLDirectAliasProc DirectAlias;
  106.   } DLLINITSTRUCT;
  107.  
  108. StructVer is 1 in ViRC 2.0pre8. ClientBuilt and ClientPre are 200 and 8,
  109. respectively. ClientName is "ViRC". DLLToken is a string that identifies
  110. this instance of the DLL and can be used with $DLL() or FreeDLL.
  111.  
  112. The VSPersist function should perform any necessary initialization or checks,
  113. then return 0 if it failed or nonzero if the DLL should be loaded. If VSPersist
  114. returns 0, the DLL will be immediately unloaded.
  115.  
  116. $DLL() uses a different format for persistent DLL calls:
  117.  
  118.   // Delphi
  119.   function p_ProcName(Active: HWND; Channel, Buffer: PChar; BufSize: Integer;
  120.     Silent: Boolean; Reserved: Pointer): Integer; stdcall;
  121.  
  122.   // C
  123.   int FAR PASCAL p_procname(HWND active, char *channel, char *buffer,
  124.     int bufsize, BOOL silent, void *reserved)
  125.  
  126. The initial "p_" allows the same DLL to have persistent and non-persistent
  127. versions of the same function. $DLL($instance foo) will actually call p_foo.
  128.  
  129. Active is the handle of the active window, and Channel is the active window's
  130. name. Buffer is used to pass parameters to and from ViRC. BufSize is the total
  131. size of the buffer. Silent is true if text output should be suppressed.
  132. Reserved is always nil in 2.0pre8, but may be used in the future.
  133.  
  134. The function must return a value between 0 and 2:
  135. 0 - no value is returned to the script.
  136. 1 - Buffer contains a string to return to the script.
  137. 2 - Buffer contains a string to be returned *and* displayed to the user.
  138.  
  139. Persistent callback functions
  140. =============================
  141.  
  142. IRCExec
  143. -------
  144. Usage: IRCExec(PChar(line));
  145.  
  146. Executes a line of script code. The line will not be evaluated first. It will
  147. be run on the global interpreter (OnServer 0).
  148.  
  149. Execute
  150. -------
  151. Usage: Execute(PChar(block));
  152.  
  153. Executes a block of script code, with lines separated by CRLF. Each line will
  154. be evaluated, as if the block were part of an alias. The code will be run on
  155. the global interpreter.
  156.  
  157. ParseVars
  158. ---------
  159. Usage: size := ParseVars(PChar(text), buffer, SizeOf(buffer));
  160.  
  161. Evaluates a string (parsing variable and function references), fills buffer
  162. with the result, and returns the total size of the result. The return value
  163. may be larger than the supplied buffer size, in which case some of the result
  164. will be cut off. The text will be evaluated on the global interpreter.
  165.  
  166. DirectAlias
  167. -----------
  168. Usage: DirectAlias(InitStruct^.DLLToken, PChar(aliasname), PChar(dllprocname));
  169.  
  170. Sets up an alias which, when run, will trigger a call to the DLL. Exactly the
  171. same as executing the block of script code:
  172.  
  173.   Alias <aliasname>
  174.     @ $fresult = $DLL(<dlltoken> <dllprocname> $1-)
  175.   EndAlias
  176.